---
title: Line Numbers
---

import ConfigVariants from '@components/ConfigVariants.astro'
import PackageManagers from '@components/PackageManagers.astro'
import { Steps, Tabs, TabItem } from '@astrojs/starlight/components'

This optional plugin allows you to display line numbers in your code blocks. The line numbers are displayed in the gutter to the left of the code.

## Installation

Before being able to display line numbers in your code blocks, you need to install the plugin as a dependency and add it to your configuration:

<Steps>

1. Add the package to your site's dependencies:

    <PackageManagers pkg="@expressive-code/plugin-line-numbers" />

2. Add the plugin to your site's configuration by passing it in the `plugins` list.

    In Astro and Starlight projects, we recommend putting this option in `ec.config.mjs` to ensure that the [`<Code>` component](/key-features/code-component/#using-an-ecconfigmjs-file) can still be used on your site.

    <ConfigVariants
      preferEcConfigFile
      imports={`
        import { pluginLineNumbers } from '@expressive-code/plugin-line-numbers'
      `}
      settings={`
        plugins: [pluginLineNumbers()],
      `}
    />

</Steps>

## Usage in markdown / MDX

### Displaying line numbers per block

You can enable or disable line numbers on individual code blocks using the `showLineNumbers` boolean prop in the **meta information** of your code blocks. This is done by appending `showLineNumbers` or `showLineNumbers=true` to your opening code fence to enable line numbers, or `showLineNumbers=false` to disable them:

````md ins=/showLineNumbers\S*/
```js showLineNumbers
// This code block will show line numbers
console.log('Greetings from line 2!')
console.log('I am on line 3')
```

```js showLineNumbers=false
// Line numbers are disabled for this block
console.log('Hello?')
console.log('Sorry, do you know what line I am on?')
```
````

The above code will be rendered like this:

```js showLineNumbers
// This code block will show line numbers
console.log('Greetings from line 2!')
console.log('I am on line 3')
```

```js showLineNumbers=false
// Line numbers are disabled for this block
console.log('Hello?')
console.log('Sorry, do you know what line I am on?')
```

:::note
You only need to use the `showLineNumbers` prop to show line numbers if you have changed the [default configuration](#configuration). By default, line numbers are enabled for all code blocks once the plugin is installed.
:::

### Changing the starting line number

By default, the line numbers of your code blocks will start at `1`. Sometimes, you might want to start at a different number to indicate that the code block is part of a larger file.

To change the starting line number for a code block, you can use the `startLineNumber` prop in the **meta information** of your code blocks. This is done by appending `startLineNumber=` followed by the desired number to your opening code fence:

````md ins=/showLineNumbers\S*/ ins=/startLineNumber\S*/
```js showLineNumbers startLineNumber=5
console.log('Greetings from line 5!')
console.log('I am on line 6')
```
````

The above code will be rendered like this:

```js showLineNumbers startLineNumber=5
console.log('Greetings from line 5!')
console.log('I am on line 6')
```

:::note
Changing the starting line number is purely visual and only affects the rendered output. Other plugins like [Text Markers](/key-features/text-markers/) are not aware of the shifted line numbers, so if you want to target specific lines for highlighting purposes, you still need to count the actual lines in the raw source code.
:::

## Usage in the `<Code>` component

The collapsible sections plugin adds the following props to the `<Code>` component that allow direct access to its features:

````yml include
name: "PluginLineNumbersProps"
headingLevel: 2
editSections:
- path: "Properties"
  replaceHeading: "Props"
- path: ""
  replaceHeading: ""
````

## Configuration

After installing the plugin, line numbers will be displayed in the gutter of all code blocks by default. You don't need to do anything else to enable this feature.

You can configure this default behavior using the `defaultProps` option in your Expressive Code configuration. You can also change the defaults by language using the sub-property `overridesByLang`:

<ConfigVariants
  preferEcConfigFile
  imports={`
    import { pluginLineNumbers } from '@expressive-code/plugin-line-numbers' // no-ins
  `}
  settings={`
    plugins: [pluginLineNumbers()], // no-ins
    defaultProps: {
      // Disable line numbers by default
      showLineNumbers: false,
      // But enable line numbers for certain languages
      overridesByLang: {
        'js,ts,html': {
          showLineNumbers: true,
        },
      },
    },
  `}
/>

## Styling

This plugin adds a `lineNumbers` object to the `styleOverrides` engine config option, allowing you to customize the visual appearance of the line numbers:

<ConfigVariants
  preferEcConfigFile
  imports={`
    import { pluginLineNumbers } from '@expressive-code/plugin-line-numbers' // no-ins
  `}
  settings={`
    plugins: [pluginLineNumbers()], // no-ins
    styleOverrides: {
      lineNumbers: {
        // Example: Change the line number foreground colors
        foreground: '#578298a6',
        highlightForeground: '#85c7ebb3',
      },
    },
  `}
/>

### Available style overrides

````yml include
name: "LineNumbersStyleSettings"
headingLevel: 2
editSections:
- path: "Properties"
  replaceHeading: ""
- path: ""
  replaceHeading: ""
replacements:
- search: '- Type: `string`$'
  replace: '- Type: [UnresolvedStyleValue](/reference/plugin-api/#unresolvedstylevalue)'
````
